package com.googlecode.bip.dao;

import java.io.Serializable;
import java.sql.SQLException;
import java.util.List;
import javax.naming.NamingException;
import com.googlecode.bip.entity.IQuestion;
import com.googlecode.bip.entity.ITopic;
import com.googlecode.bip.entity.IllegalAttributeException;
import com.googlecode.bip.entity.IllegalIdLocalException;

/**
 * DAO for {@link IQuestion}
 */
public interface QuestionDAO extends Serializable
{
    /**
     * List of idquestion for a specified topic
     *
     * @param idtopic Topic id
     * @return a List of idquestion (never null)
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public List<Integer> findQuestionIds( int idtopic )
       throws SQLException, NamingException;

    /**
     * Returns the IQuestion for this idquestion and this idlocal
     *
     * @param idquestion    idquestion to use
     * @param idlocal       idlocal to use
     * @return the IQuestion for this idquestion and this idlocal if exist, or null if not
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public IQuestion findQuestion( int idquestion, String idlocal )
       throws NamingException, SQLException;

    /**
     * Return list of all IQuestion translation for this idquestion
     *
     * @param idquestion idquestion to use
     * @return a List of IQuestion (never null)
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public List<IQuestion> findQuestions( int idquestion )
          throws NamingException, SQLException;

    /**
     * Returns a List of {@link IQuestion} for a specified topic and idlocal
     *
     * @param idtopic   Parent idtopic
     * @param idlocal   Local id for the {@link IQuestion}
     * @return a List of IQuestion (never null).
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public List<IQuestion> findQuestions( int idtopic, String idlocal )
       throws SQLException, NamingException;

    /**
     * List of {@link IQuestion} for the specified {@link ITopic} and the specified idlocal
     *
     * @param topic     Parent {@link ITopic}
     * @param idlocal   Local id for the {@link IQuestion}
     * @return a List of IQuestion (never null).
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public List<IQuestion> findQuestions( ITopic topic, String idlocal )
       throws SQLException, NamingException;

    /**
     *
     * @param name
     * @param idlocal
     * @return
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public IQuestion findQuestion( String name, String idlocal )
        throws NamingException, SQLException;

    /**
     *
     * @param name
     * @param idlocal
     * @return a List of IQuestion (never null)
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public List<IQuestion> findQuestions( String name, String idlocal )
        throws SQLException, NamingException;

//    /**
//     * <b><p>
//     * @deprecated This method does not update all fields of IQuestion
//     * </p></b>
//     * Insert a new Question (must not exist)
//     * <br/>
//     * {@link IQuestion#getIdQuestion()} value is ignored by insertion (must be equal 0)
//     * <br/>
//     * After database insert this method update {@link IQuestion#getIdQuestion()} content
//     * with the index created by database.
//     *
//     * @param iquestion IQuestion to add in database
//     * @return true if insert succeed
//     * @throws SQLException if any
//     * @throws NamingException if any
//     */
//    @Deprecated
//    public boolean insertQuestion( final IQuestion iquestion )
//        throws NamingException, SQLException;

    /**
     * Insert a new {@link IQuestion} (must not exist)
     *
     * @param idtopic       parent topic id.
     * @param minvalue      minimum value range (include)
     * @param maxvalue      maximum value range (include)
     * @param defaultvalue  default value (must be in range)
     * @param idlocal       local id
     * @param name          name according to idlocal
     * @param description   description according to idlocal
     * @return new {@link IQuestion} if insert succeed, null otherwise
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalAttributeException if arguments are inconsistent
     */
    public IQuestion insertQuestion(
           int      idtopic,
           int      minvalue,
           int      maxvalue,
           int      defaultvalue,
           String   idlocal,
           String   name,
           String   description
           )
       throws NamingException, SQLException, IllegalAttributeException;

    /**
     * Insert a new translation of {@link IQuestion}
     *
     * @param questionBase Already existing {@link IQuestion}
     * @param idlocal      New local for this {@link IQuestion}
     * @param name         Name to set
     * @param description  Description to set
     * @return new {@link IQuestion} if insert succeed, null otherwise
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalIdLocalException if idlocal not valid
     */
    public IQuestion insertQuestion(
            IQuestion   questionBase,
            String      idlocal,
            String      name,
            String      description
            )
        throws SQLException, NamingException, IllegalIdLocalException;

//    /**
//     * Insert or update a value description for a {@link IQuestion}
//     *
//     * @param idquestion
//     * @param value
//     * @param idlocal
//     * @param valueDescription
//     * @return number of row modified (0 or 1)
//     * @throws NamingException if any
//     * @throws SQLException if any
//     * @throws IllegalArgumentException if arguments are inconsistent
//     * @throws IllegalIdLocalException if idlocal is not valid
//     * @throws IllegalValueException if value is not in a valid range
//     */
//    public int updateQuestionValueDescription(
//            int     idquestion,
//            int     value,
//            String  idlocal,
//            String  valueDescription
//            )
//        throws  SQLException,
//                NamingException,
//                IllegalArgumentException,
//                IllegalIdLocalException,
//                IllegalValueException;

    /**
     * Insert or update a value description for an {@link IQuestion}
     *
     * @param iquestion         Valid {@link IQuestion}
     * @param value             Value for description
     * @param valueDescription  Text for value description
     * @return
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalAttributeException if arguments are inconsistent
     *
     * @see IQuestion#getTextValue(int)
     */
    public int updateQuestionValueDescription(
            IQuestion   iquestion,
            int         value,
            String      valueDescription
            )
        throws  SQLException,
                NamingException,
                IllegalAttributeException;

    /**
     * Update an {@link IQuestion}
     *
     * @param iquestion {@link IQuestion} to update
     * @return true if no error.
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalIdLocalException if {@link IQuestion#getIdLocal()} is not valid
     */
    public boolean updateQuestion( final IQuestion iquestion )
        throws NamingException, SQLException, IllegalIdLocalException;

    /**
     * Delete question support, if no more use.
     * Delete question support but no translation. You must delete
     * all translations before delete question support.
     *
     * @param idquestion question support to delete
     * @return true if 1 line have been deleted.
     * @throws NamingException if any
     * @throws SQLException if any
     * @see #deleteQuestionLocal(int, String)
     * @see #deleteQuestionLocals(int)
     */
    public boolean deleteQuestion( int idquestion )
        throws NamingException, SQLException;

    /**
     * Remove Question translation from database (remove Question name, Question
     * description and all value descriptions for specified local id).
     *
     * @param idquestion question translation to delete
     * @param idlocal idlocal for this translation
     * @return count of translation deleted.
     * @throws NamingException if any
     * @throws SQLException if any
     * @see #deleteQuestionLocals(int)
     * @see #deleteQuestion(int)
     */
    public int deleteQuestionLocal( int idquestion, String idlocal )
        throws NamingException, SQLException;

    /**
     * Remove ALL Question translation from database (remove Question name, Question
     * description and all value descriptions for all local id).
     *
     * @param idquestion question translations to delete
     * @return count of translation deleted.
     * @throws NamingException if any
     * @throws SQLException if any
     * @see #deleteQuestionLocal(int, String)
     * @see #deleteQuestion(int)
     */
    public int deleteQuestionLocals( int idquestion)
        throws NamingException, SQLException;

}

